Creating and Manipulating Style Objects (IM: XO)

Inside Macintosh: QuickDraw GX Objects /: Chapter 3 - Style Objects / Using Style Objects

Creating and Manipulating Style Objects
This section describes how you can create and interact with style objects as whole entities--to create, dispose of, copy, compare, and clone them. Manipulating the individual properties of style objects is described under "Manipulating Style Object Properties" beginning on page 3-10.

Creating and Deleting a Style Object
QuickDraw GX provides the GXNewStyle function to allow you to create a new style object. Before you can create a style object, you need to be in the QuickDraw GX environment. However, if you are not already in the QuickDraw GX environment, GXNewStyle calls the necessary functions for you. The functions for controlling memory use in the QuickDraw GX environment are described in the memory management chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.
Note that you can also create a new style object by copying an existing one: see the section "Copying, Comparing, and Cloning Style Objects" beginning on page 3-8.
To delete your application's reference to a style object, call the GXDisposeStyle function. Calling GXDisposeStyle may or may not actually release the memory allocated for that style object, depending on the style's owner count. GXDisposeStyle decreases the style object's owner count by 1; if that brings the owner count to zero, the style is completely deleted and its memory released. See "Manipulating a Style Object's Owner Count" beginning on page 3-11.
Owner counts and what it means to dispose of an object are described in general in the chapter "Introduction to Objects" in this book.
The following code fragment defines and creates the style object myStyle, sets some of its properties, and disposes of it:
gxStyle     myStyle;
.
.
.
myStyle = GXNewStyle ();
GXSetStylePen(myStyle, ff(2));
GXSetStyleAttributes(myStyle, gxOutsideFrameStyle);
.
.
.
if (myStyle != nil) GXDisposeStyle(myStyle);
The GXNewStyle function is described on page 3-17. The GXDisposeStyle function is described on page 3-17.

Copying, Comparing, and Cloning Style Objects
You can use the GXCopyToStyle function to copy information from one style object to another or to create a new copy of a style object.
Listing 3-1 is a code fragment that changes the type of the shape myShape to a glyph shape with four distinct style runs, and then fills out the style list, an array of style-object references in the geometry of the glyph shape. (Glyph shapes and layout shapes have style-object references in their geometries in addition to the style property that every shape object has.) The code creates new copies of the style object originally referenced by myShape, each time assigning the style reference to a position in the styleSet array and then modifying some of the style's properties. Finally, the code assigns the style list to the shape geometry.
The code in Listing 3-1 uses the library functions SetStyleCommonFont and SetStyleCommonFace to modify the font and text-face properties of the style objects it creates by copying. The text is defined in the string str, and the lengths of the style runs are defined in the runs array. (Each style run is defined to be one glyph long in this sample.)
Listing 3-1 Building a style list by copying a style object
GXSetShapeType(myShape, gxGlyphType);

/* use the default shape's style for first style run */
styleSet[0] = nil;

/* use condensed Helvetica for the second style run */
styleSet[1] = GXCopyToStyle(nil, GXGetShapeStyle(myShape));
SetStyleCommonFont(styleSet[1], helveticaFont);
SetStyleCommonFace(styleSet[1], gxCondense);

/* use extended Times for the third style run */
styleSet[2] = GXCopyToStyle(nil, GXGetShapeStyle(myShape));
SetStyleCommonFont(styleSet[2], timesFont);
SetStyleCommonFace(styleSet[2], gxExtend);

/* use 20-pt. italic Helvetica for the fourth style run */
styleSet[3] = GXCopyToStyle(nil, GXGetShapeStyle(myShape));
SetStyleCommonFont(styleSet[3], helveticaFont);
SetStyleCommonFace(styleSet[3], gxItalic);
GXSetStyleTextSize(styleSet[3], ff(20));

/* set the size (number of glyphs) of each style run */
for (counter = 0; counter < strlen(str); counter++) {
   runs[counter] = 1;               /* each run is 1 glyph long */
   styles[counter] = styleSet[counter & 3];
}
/* assign the styles array to the style list */
GXSetGlyphs(myShape, nil, nil, nil, nil, nil, runs, styles);
You can test if two style-object references refer to the same style object by simply testing the references for equality. You can also compare two different style objects for equality with the GXEqualStyle function. For two style objects to be equal, their graphic and typographic properties must have identical values, although their general object properties (owner count and tag list) do not need to be identical. Note that style object copies created with the GXCopyToStyle function are always equal to the style from which they were copied.
In certain circumstances, you may want to copy a reference to a style object without actually copying the style object. For example, you may want two variables to refer to the same style object, so that editing one of them affects both. This is called cloning a style, rather than copying a style. You can use the GXCloneStyle function to clone a style object.
Functionally, GXCloneStyle does nothing more than increase the owner count of a style object. You can clone a style with a statement such as the following:
aStyleClone = GXCloneStyle(aStyle);
This code has almost the same effect as
aStyleClone = aStyle;
that is, it sets the aStyleClone variable to reference the same style object as the aStyle variable. The difference is that GXCloneStyle also increments the style's owner count.
For more information about cloning objects, see the chapter "Introduction to QuickDraw GX" in this book. For information on manipulating style owner counts, including examples of cloning styles, see the section "Manipulating a Style Object's Owner Count" beginning on page 3-11 of this chapter.
The GXCopyToStyle function is described on page 3-18. The GXEqualStyle function is described on page 3-19. The GXCloneStyle function is described on page 3-20.

Loading and Unloading Style Objects
Although you rarely need to, you can influence memory-allocation decisions involving objects that you have created. If your application needs to have a style object in memory, you can force QuickDraw GX to load it into memory. When your application no longer needs the style object in a loaded state, you can instruct QuickDraw GX to unload it.
You call the GXLoadStyle function to make sure that a style object is in memory; if necessary, QuickDraw GX brings the object into memory from an unloaded state. You can call the GXUnloadStyle function to instruct QuickDraw GX that it is free to unload the style object at any time. These functions are described in the memory management chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.